# 技术物流

LangChain 文档由两个组成部分组成：

1. 主要文档：托管在 [python.langchain.com](https://python.langchain.com/)，这是主要面向用户的全面资源，涵盖了广泛的主题，包括教程、用例、集成等，为使用 LangChain 构建提供了广泛的指导。这些文档的内容位于 monorepo 的 `/docs` 目录中。

2. 内部代码文档：这是代码库本身的文档，也用于生成外部的 [API 参考](https://api.python.langchain.com/en/latest/langchain_api_reference.html)。API 参考的内容是通过扫描代码库中的文档字符串自动生成的。因此，我们要求开发人员对其代码进行良好的文档记录。

主要文档是使用 [Quarto](https://quarto.org) 和 [Docusaurus 2](https://docusaurus.io/) 构建的。

`API 参考` 主要是由 [sphinx](https://www.sphinx-doc.org/en/master/) 自动构建的，并由 [Read the Docs](https://readthedocs.org/) 托管。

我们感谢所有对文档的贡献，无论是修复拼写错误，添加新教程或示例，无论是在主要文档还是 API 参考中。

与代码检查类似，我们认识到文档可能会很烦人。如果您不想做这个工作，请联系项目维护人员，他们可以帮助您。我们不希望这成为贡献优秀代码的障碍。

## 📜 主要文档

主要文档的内容位于 monorepo 的 `/docs` 目录中。

文档使用 ipython 笔记本（`.ipynb` 文件）和 markdown（`.mdx` 文件）的组合编写。笔记本会使用 [Quarto](https://quarto.org) 转换为 markdown，然后使用 [Docusaurus 2](https://docusaurus.io/) 构建。

欢迎对主要文档进行贡献！🥰

修改文档后：

1. 运行 linting 和 formatting 命令（见下文）以确保文档格式良好且无错误。

2. 可选择在本地构建文档以验证更改是否正确。

3. 提交更改的 pull request。

4. 您可以通过单击 pull request `Conversation` 页面上的 `View deployment` 或 `Visit Preview` 按钮来预览和验证更改是否符合预期。这将带您到文档更改的预览页面。

## ⚒️ Linting 和本地构建文档

编写文档后，您可能希望在本地进行 linting 和构建文档，以确保文档看起来良好且没有错误。

如果您无法在本地构建它，也没关系，因为您将能够在 pull request 页面上预览文档。

### 安装依赖

- [Quarto](https://quarto.org) - 将 Jupyter 笔记本（`.ipynb` 文件）转换为用于 Docusaurus 服务的 mdx 文件的软件包。[下载链接](https://quarto.org/docs/download/)。

从 **monorepo 根目录**运行以下命令以安装依赖：

```bash
poetry install --with lint,docs --no-root
```

### 构建

构建文档的代码位于 monorepo 的 `/docs` 目录中。

在以下命令中，前缀 `api_` 表示这些是 API 参考的操作。

在构建文档之前，始终清理构建目录是一个好习惯：

```bash
make docs_clean
make api_docs_clean
```

接下来，您可以按照下面的步骤构建文档：

```bash
make docs_build
make api_docs_build
```

最后，运行链接检查器以确保所有链接都是有效的：

```bash
make docs_linkcheck
make api_docs_linkcheck
```

### Linting 和格式化

主要文档从 **monorepo 根目录** 进行 linting。要对主要文档进行 linting，请从那里运行以下命令：

```bash
make lint
```

如果您有与格式相关的错误，可以使用以下命令自动修复它们：

```bash
make format
```

## ⌨️ 内部代码文档

内部代码文档主要是由 [sphinx](https://www.sphinx-doc.org/en/master/) 从代码自动生成的，并由 [Read the Docs](https://readthedocs.org/) 托管。

为了使 API 参考有用，代码库必须有良好的文档记录。这意味着所有函数、类和方法都应该有一个文档字符串，解释它们的作用、参数是什么以及返回值是什么。这在一般情况下都是一个良好的实践，但对于 LangChain 来说尤为重要，因为 API 参考是开发人员了解如何使用代码库的主要资源。

我们通常遵循 [Google Python 风格指南](https://google.github.io/styleguide/pyguide.html#38-comments-and-docstrings) 中的文档字符串规范。

以下是一个良好文档记录函数的示例：

```python
def my_function(arg1: int, arg2: str) -> float:
    """This is a short description of the function. (It should be a single sentence.)
    This is a longer description of the function. It should explain what
    the function does, what the arguments are, and what the return value is.
    It should wrap at 88 characters.
    Examples:
        This is a section for examples of how to use the function.
        .. code-block:: python
            my_function(1, "hello")
    Args:
        arg1: This is a description of arg1. We do not need to specify the type since
            it is already specified in the function signature.
        arg2: This is a description of arg2.
    Returns:
        This is a description of the return value.
    """
    return 3.14
```

### 代码检查和格式化

对属于正在文档化的软件包的目录中的代码文档进行检查。

例如，如果你正在处理 `langchain-community` 软件包，你需要切换工作目录到 `langchain-community` 目录：

```bash
cd [root]/libs/langchain-community
```

如果还没有为该软件包设置虚拟环境，请先设置虚拟环境。

安装该软件包的依赖项：

```bash
poetry install --with lint
```

然后，你可以运行以下命令来检查和格式化代码文档：

```bash
make format
make lint
```

## 验证文档更改

将文档更改推送到存储库后，你可以通过单击拉取请求“对话”页面上的“查看部署”或“访问预览”按钮来预览和验证更改是否符合你的预期。

这将带你进入文档更改的预览页面。

此预览由 [Vercel](https://vercel.com/docs/getting-started-with-vercel) 创建。